Invoking the Linker Manually

Invoking the Linker Manually

Usually the compiler invokes the linker as the final step in compilation (as explained in "Compiler Drivers"). If object files exist that were produced by previous compilations, and you want to link them, invoke the linker by using a compiler driver instead of calling ld directly. Just pass the object filenames to the compiler driver in place of source filenames. If the original source files are in a single language, simply invoke the associated driver and specify the list of object files. (For information about linking objects derived from several languages, see "Linking Multilanguage Programs.")

A few command-line options to ld, such as -p, have different meanings when used as command-line options to cc. To pass such options to ld through an invocation of a compiler driver, use the -Wl option to the driver (see the reference page for details).

Typically, the compiler driver invokes ld as necessary. Circumstances exist under which you may need to invoke ld directly, such as when you're building a shared object or doing special linking not supported by compiler drivers (such as building an embedded system). To build C++ shared objects, use the CC driver.

Linker Syntax

A summary of ld syntax follows.

ld options object1 [object2...objectn]

options: One or more of the options listed in Table 2-3.
object: Specifies the name of the object file to be linked.

Table 2-3 contains only a partial list of linker options. Many options that apply only to creating shared objects are discussed in Chapter 3, "Using Dynamic Shared Objects." For complete information on options and libraries that affect linker processing, refer to the ld(1) reference page.

Linker Options
Option Purpose
-32 Links 32-bit programs and DSOs.
-n32 Links n32-bit programs and DSOs.
-64 Links 64-bit programs and DSOs.
-lname Specifies the name of a library, where lname is the library name. The linker searches for lname.so (and then lname.a) first in any directories specified by -L dirname options, and then in the standard directories: /usr/lib, /lib, and /usr/local/lib.
-L dirname Adds dirname to the list of directories to be searched for (as well as libraries searched for) as specified by subsequent -lname options.
-m Produces a linker memory map, listing input and output sections of the code, in System V format.
-M Produces a link map in BSD format, listing the names of files to be loaded.
-nostdlib This option must be accompanied by the -L dirname option. If the linker does not find the library in dirname list, then it does not search any of the standard library directories.
-o filename Specifies a name for your executable. If you do not specify filename, the linker names the executable a.out.
-s Strips debugging information from the program object, reducing its size. This option is useful for linking routines that are frequently linked into other program objects, but may hamper debugging.
-v Produces verbose linker output providing information about various linker passes.
-ysymname Reports all references to, and definitions of, the symbol symname. Useful for locating references to undefined symbols.

Linker Options
Option	Purpose
-32	Links 32-bit programs and DSOs.
-n32	Links n32-bit programs and DSOs.
-64	Links 64-bit programs and DSOs.
-lname	Specifies the name of a library, where lname is the library name. The linker searches for lname.so (and then lname.a) first in any directories specified by -L dirname options, and then in the standard directories: /usr/lib, /lib, and /usr/local/lib.
-L dirname	Adds dirname to the list of directories to be searched for (as well as libraries searched for) as specified by subsequent -lname options.
-m	Produces a linker memory map, listing input and output sections of the code, in System V format.
-M	Produces a link map in BSD format, listing the names of files to be loaded.
-nostdlib	This option must be accompanied by the -L dirname option. If the linker does not find the library in dirname list, then it does not search any of the standard library directories.
-o filename	Specifies a name for your executable. If you do not specify filename, the linker names the executable a.out.
-s	Strips debugging information from the program object, reducing its size. This option is useful for linking routines that are frequently linked into other program objects, but may hamper debugging.
-v	Produces verbose linker output providing information about various linker passes.
-ysymname	Reports all references to, and definitions of, the symbol symname. Useful for locating references to undefined symbols.

Linker Example

The following command tells the linker to search for the DSO libcurses.so in the directory /usr/lib. If it does not find that DSO, the linker then looks for libcurses.a in /lib.

ld foiled.o again.o -lcurses

If the linker doesn't find an appropriate library, it looks in /usr/local/lib for libcurses.a. (Note that the linker does not look for DSOs in /usr/local/lib, so don't put shared objects there.) If found in any of these places, the DSO or library is linked with the objects foiled.o and again.o; otherwise an error is generated.

Note: If the linker reports GOT overflow, GOT unreachable, or GP-related errors, see the gp_overflow(5) reference page, which describes the underlying causes of and possible solutions for overflowing the gp-relative area in the linker.